

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
  <meta charset="utf-8">
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
  <title>Creating &amp; incrementing counters &mdash; Apache Usergrid 1.0 documentation</title>
  

  
  

  

  
  
    

  

  
  
    <link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
  

  

  
    <link rel="top" title="Apache Usergrid 1.0 documentation" href="../index.html"/>
        <link rel="next" title="Retrieving counters" href="retrieving-counters.html"/>
        <link rel="prev" title="Counters &amp; events" href="events-and-counters.html"/> 

  
  <script src="../_static/js/modernizr.min.js"></script>

</head>

<body class="wy-body-for-nav" role="document">

  <div class="wy-grid-for-nav">

    
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-nav-search">
        

        
          <a href="../index.html" class="icon icon-home"> Apache Usergrid
        

        
        </a>

        
          
          
            <div class="version">
              1.0
            </div>
          
        

        
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>

        
      </div>

      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
        
          
          
              <p class="caption"><span class="caption-text">Introduction</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../introduction/overview.html">Documentation Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/usergrid-features.html">Usergrid Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/data-model.html">Usergrid Data model</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/async-vs-sync.html">Async vs. sync calls</a></li>
</ul>
<p class="caption"><span class="caption-text">Getting Started</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../getting-started/creating-account.html">Creating an Usergrid Account</a></li>
<li class="toctree-l1"><a class="reference internal" href="../getting-started/creating-a-new-application.html">Creating a new application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../getting-started/using-a-sandbox-app.html">Using a Sandbox Application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../getting-started/using-the-api.html">Using the API</a></li>
</ul>
<p class="caption"><span class="caption-text">Data Storage</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/data-store-dbms.html">The Usergrid Data Store</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/optimizing-access.html">Data Store Best Practices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/collections.html">Collections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-storage/entities.html">Entities</a></li>
</ul>
<p class="caption"><span class="caption-text">Data Queries</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/querying-your-data.html">Querying your data</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/query-parameters.html">Query parameters &amp; clauses</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/operators-and-types.html">Query operators &amp; data types</a></li>
<li class="toctree-l1"><a class="reference internal" href="../data-queries/advanced-query-usage.html">Advanced query usage</a></li>
</ul>
<p class="caption"><span class="caption-text">Entity Connections</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../entity-connections/connecting-entities.html">Connecting entities</a></li>
<li class="toctree-l1"><a class="reference internal" href="../entity-connections/retrieving-entities.html">Retrieving connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../entity-connections/disconnecting-entities.html">Disconnecting entities</a></li>
</ul>
<p class="caption"><span class="caption-text">Push Notifications</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/overview.html">Push notifications overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/adding-push-support.html">Adding push notifications support</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/getting-started.html">Getting started with push notifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/tutorial.html">Tutorial: Push notifications sample app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/registering.html">Registering with a notification service</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/creating-notifiers.html">Creating notifiers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/managing-users-and-devices.html">Managing users and devices</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/creating-and-managing-notifications.html">Creating and managing notifications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../push-notifications/troubleshooting.html">Troubleshooting</a></li>
</ul>
<p class="caption"><span class="caption-text">Security &amp; Authentication</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/app-security.html">Security &amp; token authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/using-permissions.html">Using permissions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/using-roles.html">Using roles</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/authenticating-users-and-application-clients.html">Authenticating users &amp; app clients</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/user-authentication-types.html">Authentication levels</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/changing-token-time-live-ttl.html">Changing token expiration (time-to-live)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/authenticating-api-requests.html">Authenticating API requests</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/revoking-tokens-logout.html">Revoking tokens (logout)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/facebook-sign.html">Facebook sign in</a></li>
<li class="toctree-l1"><a class="reference internal" href="../security-and-auth/securing-your-app.html">Security best practices</a></li>
</ul>
<p class="caption"><span class="caption-text">User Management &amp; Social Graph</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../user-management/user-management.html">User management &amp; social graph</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/working-user-data.html">Working with User Data</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/group.html">Working with group data</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/activity.html">Activity</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/user-connections.html">Social Graph Connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/user-connections.html#creating-other-connections">Creating other connections</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user-management/messagee-example.html">App Example - Messagee</a></li>
</ul>
<p class="caption"><span class="caption-text">Geo-location</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../geolocation/geolocation.html">Geolocating your Entities</a></li>
</ul>
<p class="caption"><span class="caption-text">Assets &amp; Files</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/uploading-assets.html">Uploading assets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/retrieving-assets.html">Retrieving assets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../assets-and-files/folders.html">Folders</a></li>
</ul>
<p class="caption"><span class="caption-text">Counters &amp; Events</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="events-and-counters.html">Counters &amp; events</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Creating &amp; incrementing counters</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#request-syntax">Request syntax</a></li>
<li class="toctree-l2"><a class="reference internal" href="#example-request">Example request</a></li>
<li class="toctree-l2"><a class="reference internal" href="#example-response">Example response</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="#decrementing-resetting-counters">Decrementing/resetting counters</a></li>
<li class="toctree-l1"><a class="reference internal" href="#using-counters-hierarchically">Using counters hierarchically</a></li>
<li class="toctree-l1"><a class="reference internal" href="retrieving-counters.html">Retrieving counters</a></li>
</ul>
<p class="caption"><span class="caption-text">Organizations &amp; Applications</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/managing.html">Organization &amp; application management</a></li>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/organization.html">Organization</a></li>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/application.html">Application</a></li>
<li class="toctree-l1"><a class="reference internal" href="../orgs-and-apps/admin-user.html">Admin user</a></li>
</ul>
<p class="caption"><span class="caption-text">API Reference</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html">Methods</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html#models">Models</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rest-endpoints/api-docs.html#sub-types">Sub-Types</a></li>
</ul>
<p class="caption"><span class="caption-text">Client SDKs</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../sdks/tbd.html">COMING SOON...</a></li>
</ul>
<p class="caption"><span class="caption-text">Installing the Stack</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../installation/ug1-deploy-to-tomcat.html">Usegrid 1: Deploying to Tomcat</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation/ug1-launcher-quick-start.html">Usegrid 1: Launcher Quick-start</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation/ug2-deploy-to-tomcat.html">Usergrid 2: Deploy to Tomcat</a></li>
</ul>
<p class="caption"><span class="caption-text">More about Usergrid</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../reference/presos-and-videos.html">Presentations &amp; Videos</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/contribute-code.html">How to Contribute Code &amp; Docs</a></li>
</ul>

          
        
      </div>
      &nbsp;
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

      
      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
        <a href="../index.html">Apache Usergrid</a>
      </nav>


      
      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="../index.html">Docs</a> &raquo;</li>
      
    <li>Creating &amp; incrementing counters</li>
      <li class="wy-breadcrumbs-aside">
        
          
            <a href="../_sources/counters-and-events/creating-and-incrementing-counters.txt" rel="nofollow"> View page source</a>
          
        
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
            
  <div class="section" id="creating-incrementing-counters">
<h1>Creating &amp; incrementing counters<a class="headerlink" href="#creating-incrementing-counters" title="Permalink to this headline">¶</a></h1>
<p>To create a new counter or increment an existing counter, include the
counter property in the body of a POST to the /events endpoint. More
than one counter can be incremented in the same request.</p>
<p><strong>Note</strong>: It may take up to 30 seconds after an event has been posted
for the counter to be incremented.</p>
<div class="section" id="request-syntax">
<h2>Request syntax<a class="headerlink" href="#request-syntax" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre>curl -X POST https://api.usergrid.com/&lt;org&gt;/&lt;app&gt;/events -d &#39;{&quot;timestamp&quot;:&lt;timestamp&gt;, &quot;counters&quot; : {&lt;counter_name&gt;:&lt;increment_value&gt;}}&#39;
</pre></div>
</div>
<p>Parameters</p>
<table border="1" class="docutils">
<colgroup>
<col width="19%" />
<col width="81%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Parameter</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>org</td>
<td>Organization UUID or organization name</td>
</tr>
<tr class="row-odd"><td>app</td>
<td>Application UUID or application name</td>
</tr>
<tr class="row-even"><td>timestamp</td>
<td>A required UNIX timestamp that specifies the time the counter is being incremented.</td>
</tr>
<tr class="row-odd"><td>counter_name</td>
<td>The name of the counter to create or the existing counter to increment.</td>
</tr>
<tr class="row-even"><td>increment_value</td>
<td>The value to increment the counter by.</td>
</tr>
</tbody>
</table>
<p>Regarding the <code class="docutils literal"><span class="pre">increment_value</span></code>, a negative number can be specified to
decrement the value. A value of &#8216;0&#8217; can be specified to reset the value
of the counter.</p>
<p>For the <code class="docutils literal"><span class="pre">timestamp</span></code>, specifying a value of 0 will automatically assign
the current time.</p>
</div>
<div class="section" id="example-request">
<h2>Example request<a class="headerlink" href="#example-request" title="Permalink to this headline">¶</a></h2>
<p>The following request will increment the &#8216;button_clicks&#8217; counter by
one, with a timestamp of the current time.</p>
<div class="highlight-python"><div class="highlight"><pre>curl -X POST https://api.usergrid.com/your-org/your-app/events -d &#39;{&quot;timestamp&quot;:0, &quot;counters&quot; : {&quot;button_clicks&quot;:1}}&#39;
</pre></div>
</div>
</div>
<div class="section" id="example-response">
<h2>Example response<a class="headerlink" href="#example-response" title="Permalink to this headline">¶</a></h2>
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
  <span class="s">&quot;action&quot;</span> <span class="p">:</span> <span class="s">&quot;post&quot;</span><span class="p">,</span>
  <span class="s">&quot;application&quot;</span> <span class="p">:</span> <span class="s">&quot;f34f4222-a166-11e2-a7f7-02e81adcf3d0&quot;</span><span class="p">,</span>
  <span class="s">&quot;params&quot;</span> <span class="p">:</span> <span class="p">{</span> <span class="p">},</span>
  <span class="s">&quot;path&quot;</span> <span class="p">:</span> <span class="s">&quot;/events&quot;</span><span class="p">,</span>
  <span class="s">&quot;uri&quot;</span> <span class="p">:</span> <span class="s">&quot;https://api.usergrid.com/your-org/your-app/events&quot;</span><span class="p">,</span>
  <span class="s">&quot;entities&quot;</span> <span class="p">:</span> <span class="p">[</span> <span class="p">{</span>
    <span class="s">&quot;uuid&quot;</span> <span class="p">:</span> <span class="s">&quot;b11217fc-9d3a-1427-b24e-699740088e05&quot;</span><span class="p">,</span>
    <span class="s">&quot;type&quot;</span> <span class="p">:</span> <span class="s">&quot;event&quot;</span><span class="p">,</span>
    <span class="s">&quot;created&quot;</span> <span class="p">:</span> <span class="mi">1401224590293</span><span class="p">,</span>
    <span class="s">&quot;modified&quot;</span> <span class="p">:</span> <span class="mi">1401224590293</span><span class="p">,</span>
    <span class="s">&quot;timestamp&quot;</span> <span class="p">:</span> <span class="mi">1401224590293</span><span class="p">,</span>
    <span class="s">&quot;counters&quot;</span> <span class="p">:</span> <span class="p">{</span>
      <span class="s">&quot;button_clicks&quot;</span> <span class="p">:</span> <span class="mi">1</span>
    <span class="p">},</span>
    <span class="s">&quot;message&quot;</span> <span class="p">:</span> <span class="n">null</span><span class="p">,</span>
    <span class="s">&quot;metadata&quot;</span> <span class="p">:</span> <span class="p">{</span>
      <span class="s">&quot;path&quot;</span> <span class="p">:</span> <span class="s">&quot;/events/b11217fc-9d3a-1427-b24e-699740088e05&quot;</span>
    <span class="p">}</span>
  <span class="p">}</span> <span class="p">],</span>
  <span class="s">&quot;timestamp&quot;</span> <span class="p">:</span> <span class="mi">1401224590291</span><span class="p">,</span>
  <span class="s">&quot;duration&quot;</span> <span class="p">:</span> <span class="mi">30</span><span class="p">,</span>
  <span class="s">&quot;organization&quot;</span> <span class="p">:</span> <span class="s">&quot;your-org&quot;</span><span class="p">,</span>
  <span class="s">&quot;applicationName&quot;</span> <span class="p">:</span> <span class="s">&quot;your-app&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="decrementing-resetting-counters">
<h1>Decrementing/resetting counters<a class="headerlink" href="#decrementing-resetting-counters" title="Permalink to this headline">¶</a></h1>
<p>To decrement a counter, specify a negative number for the counter value
in any of the above examples.</p>
<p>To reset a counter, specify a value of 0 for the counter value in any of
the above examples.</p>
<p>Note that the Usergrid JavaScript SDK also provides dedicated methods
for decrementing and resetting counters.</p>
</div>
<div class="section" id="using-counters-hierarchically">
<h1>Using counters hierarchically<a class="headerlink" href="#using-counters-hierarchically" title="Permalink to this headline">¶</a></h1>
<p>You can organize counters into hierarchies by giving them dot-separated
names, e.g. <code class="docutils literal"><span class="pre">button_clicks.homepage</span></code>. Incrementing a counter lower in
a hierarchy increments all of the counters upward in the hierarchy
chain.</p>
<p>For example, you want to log errors that your app generates, so you
create hierarchical counters for each module and function within that
module. In this example, you create the following set of counters:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">errors</span>
<span class="n">errors</span><span class="o">.</span><span class="n">module</span>
<span class="n">errors</span><span class="o">.</span><span class="n">module</span><span class="o">.</span><span class="n">function</span>
</pre></div>
</div>
<p>Incrementing <code class="docutils literal"><span class="pre">errors.module.function</span></code> by 1 increments all three
counters by 1. A hierarchy can be a useful way of easily tracking
actions in your app at both a cumulative and granular level.</p>
</div>


           </div>
          </div>
          <footer>
  
    <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
      
        <a href="retrieving-counters.html" class="btn btn-neutral float-right" title="Retrieving counters" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
      
      
        <a href="events-and-counters.html" class="btn btn-neutral" title="Counters &amp; events" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
      
    </div>
  

  <hr/>

  <div role="contentinfo">
    <p>
        &copy; Copyright 2013-2015, Apache Usergrid.

    </p>
  </div>
  Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.

</footer>

        </div>
      </div>

    </section>

  </div>
  


  

    <script type="text/javascript">
        var DOCUMENTATION_OPTIONS = {
            URL_ROOT:'../',
            VERSION:'1.0',
            COLLAPSE_INDEX:false,
            FILE_SUFFIX:'.html',
            HAS_SOURCE:  true
        };
    </script>
      <script type="text/javascript" src="../_static/jquery.js"></script>
      <script type="text/javascript" src="../_static/underscore.js"></script>
      <script type="text/javascript" src="../_static/doctools.js"></script>

  

  
  
    <script type="text/javascript" src="../_static/js/theme.js"></script>
  

  
  
  <script type="text/javascript">
      jQuery(function () {
          SphinxRtdTheme.StickyNav.enable();
      });
  </script>
   

</body>
</html>